MkDocsのライブエディタをDockerで構築してみた
MkDocsのライブエディタを構築しました。Dockerコンテナで簡単に構築できます。皆様のプロジェクトでも是非導入をご検討ください。
はじめに
データアナリティクス事業本部の藤川です。
仕様書や手順書など、社内で利用するドキュメントはオンラインストレージサービスやGitで共有されていると思います。
では、API仕様書のように外部に公開したいドキュメントはどのように作成されているでしょうか。
SphinxでしょうかMkDocsでしょうか、弊社内でも派閥が二分するようです。
私のプロジェクトでは、Markdownとの親和性を最優先にMkDocsを採用することに決めました。
そして、この度、めでたくMkDocsのライブエディタを構築できましたので、Dockerコンテナでの構築方法をご紹介したいと思います。
構築方法
３パターンご用意しました。お好きな方法を選んでください。
コンテナイメージを使用する場合
- こちらにDockerのコンテナイメージをご用意しました。
docker pullし、2回目以降/通常利用時はここからに進んでください。docker pull ghcr.io/cm-fujikawa/mkdocs:latest
リポジトリを利用する場合
- こちらにソースコードをご用意しました。
git cloneし、2回目以降/通常利用時はここからに進んでください。git clone https://github.com/cm-fujikawa/mkdocs.git
一から構築する場合
MkDocs初期設定に進んでください。
MkDocs初期設定
初回のみ/リポジトリに作成済み
documentフォルダを作成し、必要なフォルダ構成（docs、site）を作ります。mkdir document && cd document mkdir docs mkdir site
mkdocs.ymlファイルを作成します。vi mkdocs.yml
- リポジトリに保存する場合は、
.gitignoreファイルを作成します。vi .gitignore
siteフォルダをリポジトリに登録しないよう設定します。site/
コンテナ構築方法
初回のみ/リポジトリに作成済み
- Dockerfileを作成します。
vi Dockerfile
- Dockerfile
FROM alpine WORKDIR /document RUN apk update && \ apk add --no-cache python3 py3-pip && \ pip3 install --upgrade pip && \ pip3 install mkdocs mkdocs-material fontawesome_markdown EXPOSE 8000 CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]
利用方法
初回のみ
- コンテナイメージを作成します。
docker build . -t ghcr.io/cm-fujikawa/mkdocs:latest
2回目以降/通常利用時はここから
- コンテナを起動します。
docker run --rm --name mkdocs \ -d -p 8000:8000 -v ${PWD}/document:/document ghcr.io/cm-fujikawa/mkdocs:latest - http://localhost:8000にアクセスすると、MkDocsが表示されます。（Markdownファイルがないため、本文は404エラーとなっています）
ドキュメントの編集・確認方法
docsフォルダにあるmkdocs.ymlファイル、documentフォルダ配下のMarkdownファイルを編集してください。- リアルタイムに、編集内容がブラウザ表示に反映されます。
- こちらにある
mkdocs.ymlファイルで試してみました。 - そのままでは、エラーとなるため、次の行をコメントアウトするか、Dockerfileファイルに
fontawesome_markdownを加えて、pip3 install mkdocs mkdocs-material fontawesome_markdownのように編集して、コンテナを再構築してください。- fontawesome_markdown
- 当然ですが、同じ結果が得られました。（Markdownファイルがないため、本文は404エラーとなっています）
作業終了時
- コンテナを停止します。
--rmオプションを指定しているので、コンテナは削除されます。docker stop mkdocs
さいごに
MkDocsは、YAML形式の設定ファイルとMarkdown形式のドキュメントからリッチなデザインの仕様書を簡単に出力できます。
テキストファイルですので、Gitリポジトリで版管理できます。いつ、誰がどのような理由で更新したのか履歴を残せますし、デグレや誤った文書を公開してしまうリスクを軽減できるでしょう。
今回ご紹介したライブエディタも、MkDocsの設定ファイルに合わせて、プラグインを追加し、リポジトリで配信できるのでメンテナンスの手間も軽減できます。
簡単に構築できて、良いこと尽くめなので、皆様のプロジェクトでも是非導入をご検討ください。
